PBAllocContigSync

PBAllocContigSync
Header:	Files.h		Carbon status:	Supported

Allocates additional contiguous blocks to an open file.

OSErr PBAllocContigSync (
    ParmBlkPtr paramBlock
);

paramBlock: A pointer to a basic File Manager parameter block.

function result: A result code.

DISCUSSION

The relevant fields of the parameter block are:

ioCompletion

On input, a pointer to a completion routine.
ioResult

On output, the result code of the function.
ioRefNum

On input, a file reference number to the file to which to add blocks.
ioReqCount

On input, the number of bytes to allocate.
ioActCount

On output, the number of bytes actually allocated, rounded up to the nearest multiple of the allocation block size.

The PBAllocContigSync function is identical to the PBAllocateSync function except that if there isn’t enough contiguous empty space on the volume to satisfy the allocation request, PBAllocContigSync does nothing and returns dskFulErr as its function result. If you want to allocate whatever space is available, even when the entire request cannot be filled by the allocation of a contiguous piece, call PBAllocateSync instead.

The File Manager automatically allocates file blocks if you move the logical end-of-file past the physical end-of-file, and it automatically deallocates unneeded blocks from a file if you move the logical end-of-file to a position more than one allocation block before the current physical end-of-file. Consequently, you do not in general need to be concerned with allocating or deallocating file blocks. However, you can improve file block contiguity if you use the PBAllocContigSync function to preallocate file blocks. This is most useful if you know in advance how big a file is likely to become.

PBAllocContigSync is not supported by AppleShare volumes. Instead, use SetEOF or PBSetEOFSync to extend a file by setting the end-of-file.

AVAILABILITY

Supported in Carbon. Available in Mac OS 8.1 and later when Carbon 1.0.2 or later is present.